ci: introduce towncrier for fragment-based changelog management by MikeGoldsmith · Pull Request #16 · open-telemetry/opentelemetry-python-genai

MikeGoldsmith · 2026-05-14T13:22:07Z

Summary

Adopt towncrier for fragment-based changelog management. PRs with user-visible impact add a file under <package>/.changelog/<PR>.<type> rather than editing CHANGELOG.md, which removes the merge-conflict footgun on backports and concurrent PRs.

Every publishable package here releases independently, so each gets its own [tool.towncrier] config and .changelog/ directory — mirroring the independent-package pattern in opentelemetry-python-contrib.

What's in this PR:

[tool.towncrier] block in each package's pyproject.toml (7 instrumentations + util-genai)
<package>/.changelog/.gitignore per package
Do-not-edit comment and  marker above each existing ## Unreleased heading
Shared template at scripts/changelog_template.j2
.github/workflows/changelog.yml: blocks direct CHANGELOG.md edits, requires a fragment, previews rendered changelogs per package; skipped via the Skip Changelog label
tox -e changelog-preview for local previewing
towncrier in root dev dependencies
CONTRIBUTING.md updated with fragment authoring instructions, and a condensed version added to AGENTS.md

Part of #15.

Notes

This PR carries the Skip Changelog label since the change is pure tooling.
The Skip Changelog and Stale labels were created on this repo as a prerequisite. prepare-release is intentionally not created yet — to be added when release tooling lands (planned name: Prepare Release).
Verified locally that the per-package draft renders correctly with a throwaway fragment and that tox -e changelog-preview runs cleanly across all 8 packages.

Replace manual CHANGELOG.md editing with towncrier fragments. Each PR adds a small file under <package>/.changelog/ instead of editing CHANGELOG.md directly, eliminating merge conflicts on backports and concurrent PRs. Every publishable package in this repo releases independently, so each gets its own [tool.towncrier] config and .changelog/ directory. Changes: - Add [tool.towncrier] block to each package's pyproject.toml (7 instrumentations + util-genai) - Add .changelog/.gitignore stub per package - Insert do-not-edit comment and  marker above the Unreleased header in each CHANGELOG.md - Add shared scripts/changelog_template.j2 - Add .github/workflows/changelog.yml: blocks direct CHANGELOG.md edits, requires a fragment, previews the rendered changelog per package. Skipped via the "Skip Changelog" label - Add tox -e changelog-preview for local previewing - Add towncrier to root dev dependencies - Update CONTRIBUTING.md with fragment authoring instructions Assisted-by: Claude Opus 4.7 (1M context)

- Remove changelog-preview from tox envlist so the workflow generator doesn't create a CI job for it. The env stays available for local use and the changelog.yml workflow already runs the preview in CI. - Regenerate uv.lock with the index URL form the uv-lock pre-commit hook uses (trailing slash), matching upstream. Assisted-by: Claude Opus 4.7 (1M context)

lmolkova

Not sure if it's ready for review, but looks great on the first sight!

Addresses review feedback on PR open-telemetry#16 to mirror the new CONTRIBUTING.md guidance for AI-assisted contributions in a more concise form. Assisted-by: Claude Opus 4.7 (1M context)

MikeGoldsmith · 2026-05-14T18:35:20Z

Ready for review now - I left it in draft while I fixed up the 'Skip Changelog' label, which is working now 👍🏻

Copilot

Pull request overview

This PR introduces towncrier-based changelog management across the independently released packages in the repository, replacing direct CHANGELOG.md edits with per-package changelog fragments.

Changes:

Adds towncrier configuration and .changelog/ directories for instrumentation packages and opentelemetry-util-genai.
Adds changelog preview support via tox, a shared towncrier template, and a new GitHub Actions changelog check.
Updates contributor/agent documentation and root dev dependencies for the new changelog workflow.

Reviewed changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
`.github/workflows/changelog.yml`	Adds CI enforcement and previewing for changelog fragments.
`AGENTS.md`	Documents changelog fragment expectations for agents.
`CONTRIBUTING.md`	Replaces direct changelog instructions with towncrier fragment guidance.
`pyproject.toml`	Adds towncrier to the root dev dependency group.
`scripts/changelog_template.j2`	Adds the shared towncrier rendering template.
`tox.ini`	Adds the `changelog-preview` tox environment.
`uv.lock`	Locks towncrier and its transitive dependencies.
`instrumentation/opentelemetry-instrumentation-anthropic/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-anthropic/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-anthropic/pyproject.toml`	Adds package-specific towncrier configuration.
`instrumentation/opentelemetry-instrumentation-claude-agent-sdk/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-claude-agent-sdk/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-claude-agent-sdk/pyproject.toml`	Adds package-specific towncrier configuration.
`instrumentation/opentelemetry-instrumentation-google-genai/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-google-genai/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-google-genai/pyproject.toml`	Adds package-specific towncrier configuration.
`instrumentation/opentelemetry-instrumentation-langchain/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-langchain/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-langchain/pyproject.toml`	Adds package-specific towncrier configuration.
`instrumentation/opentelemetry-instrumentation-openai-agents-v2/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-openai-agents-v2/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-openai-agents-v2/pyproject.toml`	Adds package-specific towncrier configuration.
`instrumentation/opentelemetry-instrumentation-openai-v2/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-openai-v2/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-openai-v2/pyproject.toml`	Adds package-specific towncrier configuration.
`instrumentation/opentelemetry-instrumentation-weaviate/CHANGELOG.md`	Adds towncrier management notice and marker.
`instrumentation/opentelemetry-instrumentation-weaviate/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`instrumentation/opentelemetry-instrumentation-weaviate/pyproject.toml`	Adds package-specific towncrier configuration.
`util/opentelemetry-util-genai/CHANGELOG.md`	Adds towncrier management notice and marker.
`util/opentelemetry-util-genai/.changelog/.gitignore`	Keeps the changelog fragment directory tracked.
`util/opentelemetry-util-genai/pyproject.toml`	Adds package-specific towncrier configuration.

- Re-trigger the changelog workflow on labeled/unlabeled events so adding the "Skip Changelog" label without pushing a new commit is enough to clear a previously failed run. - Validate fragment basenames against <PR_NUMBER>.<type> in the workflow, catching typos in either the PR number or the fragment type before they ship a misleading changelog link. - Note in each CHANGELOG.md do-not-edit comment that the existing static "## Unreleased" entries must be folded into the first towncrier-built release manually. Assisted-by: Claude Opus 4.7 (1M context)

lmolkova · 2026-05-14T19:08:52Z

+  containing a one-line description. Types: `added`, `changed`, `deprecated`, `removed`, `fixed`.
+- Don't include the PR number in the body — towncrier appends it from the filename.
+- Preview locally with `uv run tox -e changelog-preview`.
+- If the change needs no entry (pure docs or tooling), add the `Skip Changelog` label to the PR.


I think this might send agents on a wrong path - most contributors don't have write access but their agents might try to add labels. let's remove?

Suggested change

- If the change needs no entry (pure docs or tooling), add the `Skip Changelog` label to the PR.

lmolkova · 2026-05-14T19:09:33Z

+- Preview locally with `uv run tox -e changelog-preview`.
+- If the change needs no entry (pure docs or tooling), add the `Skip Changelog` label to the PR.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md#4-update-the-changelog) for full details.


Suggested change

See [CONTRIBUTING.md](CONTRIBUTING.md#4-update-the-changelog) for full details.

it's already linked somewhere in this doc, no need to repeat

Addresses Copilot review feedback: the changelog steps depend on open-telemetry#16 (towncrier setup) which hasn't merged yet. Make the dependency explicit at the top of the doc so it's obvious to any reviewer. Assisted-by: Claude Opus 4.7 (1M context)

The note belongs in the PR description as a merge-ordering signal, not in the doc itself where it would have to be removed once open-telemetry#16 lands. Assisted-by: Claude Opus 4.7 (1M context)

MikeGoldsmith added the Skip Changelog PR does not require a changelog entry label May 14, 2026

lmolkova reviewed May 14, 2026

View reviewed changes

Comment thread CONTRIBUTING.md

lmolkova reviewed May 14, 2026

View reviewed changes

add condensed changelog guidance to AGENTS.md

6d05257

Addresses review feedback on PR open-telemetry#16 to mirror the new CONTRIBUTING.md guidance for AI-assisted contributions in a more concise form. Assisted-by: Claude Opus 4.7 (1M context)

MikeGoldsmith marked this pull request as ready for review May 14, 2026 18:34

MikeGoldsmith requested a review from a team as a code owner May 14, 2026 18:34

Copilot AI review requested due to automatic review settings May 14, 2026 18:34

Copilot started reviewing on behalf of MikeGoldsmith May 14, 2026 18:35 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

lmolkova approved these changes May 14, 2026

View reviewed changes

This was referenced May 15, 2026

ci: validate changelog fragment filenames open-telemetry/opentelemetry-python#5212

Open

ci: validate changelog fragment filenames open-telemetry/opentelemetry-python-contrib#4586

Open

ci: add PR and issue templates #19

Open

docs: add RELEASING.md #20

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci: introduce towncrier for fragment-based changelog management#16

ci: introduce towncrier for fragment-based changelog management#16
MikeGoldsmith wants to merge 4 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/setup-towncrier

MikeGoldsmith commented May 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

lmolkova left a comment

Uh oh!

MikeGoldsmith commented May 14, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmolkova May 14, 2026

Uh oh!

lmolkova May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

MikeGoldsmith commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes

Uh oh!

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith commented May 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lmolkova May 14, 2026

Choose a reason for hiding this comment

Uh oh!

lmolkova May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MikeGoldsmith commented May 14, 2026 •

edited

Loading